---
title: Spread Plugin
description: Configure the PDF viewer to display pages individually or in a two-page, book-like spread layout.
searchable: true
---

# Spread Plugin

The Spread Plugin controls the page layout, allowing you to switch between a single-page view and a two-page "spread" view, similar to an open book. This plugin is purely logical; it changes how pages are grouped before being rendered, without providing any UI components itself.

## Installation

The plugin is available as a separate NPM package.

```sh npm2yarn
npm install @embedpdf/plugin-spread
````

## Registration

Import `SpreadPluginPackage` and add it to the `plugins` array. You can configure the default layout mode when the viewer loads.

```tsx {4, 14-16}
import { createPluginRegistration } from '@embedpdf/core'
import { EmbedPDF } from '@embedpdf/core/react'
// ... other imports
import { SpreadPluginPackage, SpreadMode } from '@embedpdf/plugin-spread/react'

const plugins = [
  // ... other essential plugins
  createPluginRegistration(LoaderPluginPackage, { /* ... */ }),
  createPluginRegistration(ViewportPluginPackage),
  createPluginRegistration(ScrollPluginPackage),
  createPluginRegistration(RenderPluginPackage),

  // Register and configure the spread plugin
  createPluginRegistration(SpreadPluginPackage, {
    defaultSpreadMode: SpreadMode.None,
  }),
]
```

## Usage

The plugin provides the `useSpread` hook to control the layout mode. When you change the mode, the plugin recalculates the page groupings, and the `<Scroller>` component automatically updates to reflect the new layout.

### Building a Spread Mode Toolbar

Use the `useSpread` hook to get the current `spreadMode` and the `provides` object for changing it. You can then build a UI, like a set of buttons, to allow users to switch between layouts.

```tsx {2, 5}
import { SpreadMode } from '@embedpdf/plugin-spread';
import { useSpread } from '@embedpdf/plugin-spread/react';

export const SpreadToolbar = () => {
  const { provides: spread, spreadMode } = useSpread();

  if (!spread) return null;

  return (
    <div>
      <span>Current Layout: {spreadMode}</span>
      <button onClick={() => spread.setSpreadMode(SpreadMode.None)}>Single Page</button>
      <button onClick={() => spread.setSpreadMode(SpreadMode.Odd)}>Two-Page (Odd)</button>
      <button onClick={() => spread.setSpreadMode(SpreadMode.Even)}>Two-Page (Even)</button>
    </div>
  );
};
```

## Live Example

This example shows a viewer with a toolbar that lets you dynamically change the page layout.

import { PDFViewer } from '../code-examples/spread-example';

<PDFViewer />

## API Reference

### Configuration (`SpreadPluginConfig`)

| Option | Type | Description |
| :--- | :--- | :--- |
| **`defaultSpreadMode`** | `SpreadMode` | Sets the initial page layout when a document is loaded. \<br /\>**Default**: `SpreadMode.None` |

### Hook: `useSpread()`

Connects your component to the spread plugin's state and functions.

#### Returns

| Property | Type | Description |
| :--- | :--- | :--- |
| **`spreadMode`** | `SpreadMode` | The current reactive spread mode (`'none'`, `'odd'`, or `'even'`). |
| **`provides`** | `SpreadCapability \| null` | An object with methods to control the layout, or `null` if the plugin is not ready. |

#### `SpreadCapability` Methods

| Method | Description |
| :--- | :--- |
| **`setSpreadMode(mode)`** | Sets the layout to the specified `SpreadMode`. This will cause the viewer to re-render with the new page groupings. |
| **`getSpreadMode()`** | Returns the current `SpreadMode`. |

### `SpreadMode` Enum

The `SpreadMode` determines how pages are grouped together.

| Mode | Description | Page Grouping Example |
| :--- | :--- | :--- |
| **`None`** | The default view. Each page is displayed individually. | `[[p1], [p2], [p3], ...]` |
| **`Odd`** | Pages are paired up, starting from the first page. Ideal for documents where page 1 is on the right-hand side of a spread (like a magazine). | `[[p1, p2], [p3, p4], ...]` |
| **`Even`** | The first page is shown by itself, and subsequent pages are paired. Ideal for books where the cover (page 1) is a standalone page. | `[[p1], [p2, p3], [p4, p5], ...]` |